home *** CD-ROM | disk | FTP | other *** search
/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / c / tcombo.exe / TCOMBO.TXT < prev    next >
Text File  |  1992-11-18  |  7KB  |  190 lines
  1. Introduction
  2.  
  3. I have seen many requests in the Turbo Vision forum for a Combo Box class
  4. similar to the one available in Microsoft Windows.  Here is a family of
  5. classes that provide the functionality of the Windows Combo Box.
  6.  
  7. Combo Box Classes
  8.  
  9. There are three classes that make up the Combo Box family:  TComboBox,
  10. TComboWindow, and TComboViewer.  TComboBox provides the icon in the dialog
  11. box that represents the whole TComboBox; by clicking on the icon or pressing
  12. the down arrow while the linked TInputLine is selected, the Combo Box
  13. selection window becomes active.  The selection window is made up of a
  14. TComboWindow, a TComboViewer, and a TScrollBar.  While active, the
  15. TComboWindow is the modal view; clicking outside of the window area causes
  16. the TComboWindow to terminate with a cmCancel command.
  17.  
  18. The TComboBox is only one character wide, so it should be place directly
  19. after the inputline to which it will be linked.  For example:
  20.  
  21.    tv = new TInputLine(TRect(2,2,20,3), 25);
  22.    insert(tv);
  23.    insert(new TComboBox(TRect(20,2,21,3), tv, list));
  24.  
  25. The TComboWindow automatically sizes itself to be as wide as the inputline
  26. and the combo box together.
  27.  
  28. When used with a regular TInputLine, TComboBox acts just like a THistory
  29. object.  However, when used with the TStaticInputLine (also in this zip
  30. file), TComboBox acts like a Combo Box in Windows, only allowing those items
  31. already in the list to be selected.
  32. Class Descriptions
  33.  
  34. TComboBox
  35.  
  36. TComboBox  implements a pick listof items for the user to choose.  When used
  37. with a standard TInputLine, it acts very much like a THistory object.  If
  38. used with a TStaticInputLine, only the items which are currently in the list
  39. can be selected.
  40.  
  41. Data Members
  42. char *icon;
  43.      Points to the character that is used by the draw() function to display
  44.      the icon on the screen.
  45.  
  46. TInputLine *link;
  47.      Points to the related TInputLine, or a descendant of TInputLine.  Used
  48.      to update the TInputLine data member when an item is selected from the
  49.      list.
  50.  
  51. TCollection *list;
  52.      Points to the list of items that are currently available for selection
  53.      by the user.  This list is updated whenever the selected state of link
  54.      is changed.
  55.  
  56. Member Functions
  57. TComboBox(TRect& bounds, TInputLine *aLink, TCollection *aList);
  58.      Constructs a new TComboBox.  If the extent of bounds is greater than a
  59.      1 by 1 square, the extent is changed to that size.
  60.  
  61. virtual ushort dataSize();
  62.      Returns the size of the data read or written by getData and setData.
  63.      Currently returns sizeof(void *).
  64.  
  65. virtual void draw();
  66.      Draws the character pointed to by icon in the specified color.
  67.  
  68. virtual void getData(void *rec);
  69.      Returns a pointer to list in rec.
  70.  
  71. TPalette& getPalette() const;
  72.      Returns the defined palette cpComboBox.
  73.  
  74. virtual void handleEvent(TEvent& event);
  75.      Handles mouse events and a down arrow key event to open a TComboWindow.
  76.  
  77. virtual void newList(TCollection *aList);
  78.      Sets a new list for TComboBox by first deleting the old list and then
  79.      setting list to aList.
  80.  
  81. virtual void setData(void *rec);
  82.      Reads a pointer from rec and assigns it to list.
  83.  
  84.  
  85.  
  86. void shutDown();
  87.      Sets link = 0 and list = 0, then calls TView::shutDown().  Deleting the
  88.      actual TCollection is the responsibility of the program; this provides
  89.      for a persistent list between calls to the same dialog box.
  90. TComboViewer
  91.  
  92. TComboViewer is a descendant of TListViewer; it provides the actual list
  93. viewing mechanism for the TComboBox.
  94.  
  95. Data Members
  96. TCollection *list;
  97.      Points to the list of items that are currently available for selection
  98.      by the user.  This list is updated whenever the selected state of link
  99.      is changed.
  100.  
  101. Member Functions
  102. TComboViewer(const TRect& bounds, TCollection *aList, TScrollBar *sb);
  103.      Constructs a TComboViewer by setting list = aList and calling
  104.      TListViewer(bounds, 1, 0, sb).
  105.  
  106. virtual ushort dataSize();
  107.      Returns the size of the data read and written by getData and setData.
  108.  
  109. TPalette& getPalette() const;
  110.      Returns the defined palette cpComboViewer.
  111.  
  112. virtual void getData(void *data);
  113.      Accepts data in the format of a TListBoxRec.
  114.  
  115. virtual void getText(char *dest, short item, short maxLen);
  116.      Returns the itemth item from list in dest, not copying more than maxLen
  117.      characters.
  118.  
  119. virtual void handleEvent(TEvent& event);
  120.      Checks for keyboard or mouse events that will end the modal view of
  121.      TComboViewer.  All other events are passed on to
  122.      TListViewer::handleEvent.
  123.  
  124. virtual void newList(TCollection *aList);
  125.      Accepts a new list to be displayed, and disposes of the old list.
  126.  
  127. virtual void setData(void *data);
  128.      Returns data in the format of a TListBoxRec.
  129.  
  130. void shutDown();
  131.      Sets list = 0, then calls TListViewer::shutDown().  Disposing of the
  132.      list is the responsibility of the programmer.
  133. TComboWindow
  134.  
  135. Data Members
  136. TComboViewer *viewer;
  137.      A pointer to the TComboViewer that is a subview of TComboWindow.
  138.  
  139. Member Functions
  140. TComboWindow(const TRect& bounds, TCollection *aList);
  141.      Calls TWindow(bounds, 0, 0), the creates a TComboViewer and a TScrollBar
  142.      to fit within its bounds.  The aList parameter is passed on to
  143.      TComboViewer.
  144.  
  145. TPalette& getPalette() const;
  146.      Returns the defined palette cpComboWindow.
  147.  
  148. void getSelection(char *dest);
  149.      Returns in dest the item selected from the list.
  150.  
  151. virtual void handleEvent(TEvent&);
  152.      Checks for mouse events outside of the bounds of TComboWindow; all other
  153.      events are passed on to TWindow::handleEvent.
  154.  
  155. void setSelection(char *data);
  156.      Sets the selected item in the list to data.
  157. TStaticInputLine
  158.  
  159. Data Members
  160. TCollection *list;
  161.      Points to the list of items that are currently available for selection
  162.      by the user.  This list is updated whenever the selected state of link
  163.      is changed.
  164.  
  165. Member Functions
  166. TStaticInputLine(const TRect& bounds, int maxLen, TCollection *aList);
  167.      Created a TStaticInputLine by setting list = aList, and calling
  168.      TInputLine(bounds, maxLen).
  169.  
  170. virtual void getNextMatch();
  171.      A replacement for the call to matchFirstChar().  Currently getNextMatch
  172.      calls matchFirstChar(), but later versions will have an algorithm to
  173.      provide a circular search queue making TStaticInputLine behave more like
  174.      Windows.
  175.  
  176. virtual void handleEvent(TEvent& event);
  177.      Handles most keyboard events for TStaticInputLine; keyboard events
  178.      handled include all printable characters, up and down arrow keys.  All
  179.      other events are passed on to TInputLine::handleEvent.
  180.  
  181. virtual void newList(TCollection *aList);
  182.      Accepts a new list to be displayed, and disposes of the old list.
  183.  
  184.  
  185. Boolean matchFirstChar(void *, void *);
  186.      matchFirstChar is not a member or a friend function of TStaticInputLine,
  187.      but is called by TStaticInputLine::handleEvent.  This function is of
  188.      type ccTestFunc and is used to test if the first characters of the two
  189.      items passed are the same.  This function is case insensitive.
  190.